Handling user input

You can set how and which elements in your application react to user input. In Kanzi, to handle user input you can:

For these Kanzi nodes you do not have to create input manipulators manually, because they handle input by default:

Use triggers and actions to create interactions based on user input. See Using triggers.

Using input manipulators

Kanzi provides low and high-level access to input:

Kanzi provides input manipulators to enable gesture recognition for nodes in your Kanzi project. You can assign the manipulators through the API.

Kanzi provides these input manipulators:

InputManipulator is the base class for manipulators, and functions such as ClickManipulator::create and PanManipulator::create create input manipulators responsible for the corresponding gesture recognition.

When you create an input manipulator, to recognize the gesture, attach it to the node with Node::addInputManipulator. This attaches all the children of the node too.

Attached manipulator generates messages in response to user actions. Each manipulator uses messages to report different events during gesture recognition, such as PanManipulator::StartedMessage, PanManipulator::MovedMessage, PanManipulator::FinishedMessage for the pan manipulator and so on.

Defining which node receives user input

When you create your user interface take special care how your application handles user input, because only one node can receive user input at a time. For example, define whether a click is handled by the node in the front or by the one behind it.

Kanzi uses hit testing to determine the nodes that receive input. In practice, hit testing projects a ray from the camera towards the 3D scene based on the screen coordinates of the input event.

By default hit testing is enabled for the Button, List Box Item Container, Scroll View, and Slider nodes. To enable hit testing for a node of any other node type, add and enable the Hit Testable property to that node.

The first node from the Camera node whose bounding box is intersected and has the Hit Testable property enabled, receives the input, consumes the event, and generates set actions, such as sending a click message.

For example, if you place two Box nodes so that the BoxFront node is in front of the BoxRear node and occludes it completely:

Setting the size of the input area

When you want to change the area within which a node receives input, use the Hit Testable Container property. In Kanzi hit testing for all nodes is by default based on the layout size of each node. Use the Hit Testable Container property to include in the input area the layout size of the node that has the property and the layout size of any of its child nodes, rather than just the bounding volume of the node.

By default the Hit Testable Container property is enabled for the Button, List Box Item Container, Scroll View, and Slider 3D nodes. To set the size of the input area for a node of any other node type, add and enable the Hit Testable Container and Hit Testable properties.

For example, a Stack Layout 3D node which contains a Box node receives click input:

See also

Handling keyboard input

Using the click manipulator

Using the long-press manipulator

Using the multi-click manipulator

Using the drag-and-drop manipulator

Using the pan manipulator

Using the pinch manipulator

Using the Button nodes

Using the Toggle Button nodes

List Box nodes

Using the List Box Item Container prefabs

Using the Scroll View nodes

Using the Slider nodes

Using triggers